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Introduction By The Editor 


This instruction manual is derived from the instruction pamphlet provided for 
the Larken Disk Editor by Larry Kenny when the program was originally issued in 
1988. 


Most of the editing was done for the sake of saving the reader's eye-sight 
and for easier transfer to electronic media such as this web site. Otherwise, this 
instruction manual is as Larry Kenny wrote it. 


There are a few other things that should be noted: 


1)A "disk" usually means a double-sided, double-density 5% inch floppy 
diskette. A few Timex/Sinclairusers did have 5% inch 
quad-density drives at that time and 3% inch drives were just 
becoming popular. 


2)Any text that has been "struck-out" indicates that this was part of the 
original pamphlet but the goods and services are no longer being 
offered. 


3)Finally, | wish to remind the reader that this is copyrighted material. It 
is provided for users of the original software who require a manual 
or for personal reference. For reproduction for any other purpose, 
please write for permission to the e-mail address given below. 


David Solly 

Bibliotheca Sagittarii 
Ottawa, Ontario 

© 9 November 1998 
ac355@freenet.carleton.ca 
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The Larken editor is a useful tool for modifying, repairing or examining the 
directory, track map and data on a disk 





LKDOS Disk Organization 


Before you use the Disk Editor on a disk, you should have an understanding 
of how the disk is organized and how a program is stored on the disk. 


The disk is divided into 5 Kilobyte blocks. Each block is comprised of ten 
512-byte sectors, however, only the entire block can be accessed. 


On a 40-track, double-sided, double-density disk there are 80 blocks. Ona 
40-track, single-sided, double-density disk there are 40 blocks. Ona 
quad-density, (80-track, double-sided), there are 160 blocks. The blocks are 
numbered starting at track 0, side 0 — track 0 is the farthest from the centre of 
the disk. Block1 is track 0, side 1. All even numbered blocks are on side 0 
and all odd numbered blocks are on side 1. 


Organization of Blocks 


Side 1: 1 3 5 7 9 11 13 15 17 19 >> 
Side 0: 0 2 4 6 8 10 12 14 16 18 -> 


Block 0 is reserved for the catalogue, track map and disk name. The track 
map is a 165-byte table beginning at address 24 in block 0. The map is used 
when saving to let LKDOS know whatblocks on the disk are available (unused). 


The track map is created according to the number of tracks and sides 
entered when the diskis formatted. Numbers starting from 0 are listed 
sequential up to a possible 164 blocks. Any blocks that do not exist on the 
actual disk or are reserved, (block 0 is reserved for the catalogue), are replaced 
with the number245. LKDOS uses numbers from 245 to 255 as markers in the 
catalogue. 
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Example: 
If a 40-track, single-sided disk was formatted, the track map 
would show all odd numbered blocks as 245 (used) as well as 
the even number blocks past the 40 track limit. 


When a file is saved, the blocks that the file uses are replaced by 245 in the 
track map. When afileis deleted, the blocks used by the file are restored in the 
track map with the block number. If you save a file with a name that is already 
on the disk, the existing file is first erased before the new file is saved. 


Following the track map are the directory name cells. Thisis a list of about 
100 formatted areas for storing the file name of each file and the blocks used by 
that file. The length of each cell is 34 bytes butthis may vary if the file is a 
custom type file. 
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Markers 


Each cell begins with a 255 marker. Then a 9-character filename. Ifthe 
cell is not used or the file has been deleted, then a 253 marker follows the 255. 
After the file name is a 253 marker marking the beginning of the block list used 
by the file. 


The end of the block list is marked by 249. The 249 isa floating marker. If 
the file is deleted it is moved to just after the 253 indicating no blocks used. 
There is room in each cell for 21 blocks, — over 100K — butthis can be 
expanded for sequential files etcetera. On the other hand, if you would like 
more that 100 files per disk for a quad-density drive that has 160 blocks, you can 
reduce the size of the block area so you can putmore name cells. 


The end of the list of 100 or so name cells is marked by a 250. At address 
4500 in the catalogue block is the disk name. It can be very long — over 500 
characters — andends with a 0. 


MARKERS USED BY LKDOS IN THE CATALOGUE BLOCK (BLOCK 0) 
245 -Blockin use. Only used in track map. 
249 -Marks the end of the block list in the name cell. 
250 -Marks the end of the directory name cells. 
253 -Marks the beginning of the block list in the name cell. 
254 -Follows the 255 marker if the cell is notin use. 
255 -Marks the beginning of each directory name cell. 

Also, in block 0, address 20 hold the number of sides on the disk, address 


21 holds the number of tracks, and address 22 holds the head speed. The head 
speed is the speed at which the disk drive's head steps from track to track. 
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Data Blocks 


All blocks from block 1 up to the maximum on the disk are data blocks. 
Each data block contains a 24-byte information header and then room for 5090 
bytes of data. 


Header Information 


Address Description 
In 
Block 


fo Rene 
24 


22, 23 Total length of file 


20, 21 - Variable - Prog (Offset for BASIC) 
au | Start of data (5090 bytes, maximum). 
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Disk Editor Commands 


When using the Disk Editor you should have the write protect sticker 
removed from the disk you wantto edit or modify. The routines used in the Disk 
Editor can notdetect the presence of a write protect sticker 


EDIT Data On Disk 


Selecting this will display a windowed screen with a prompt to enter a block 
number to load into the buffer. You can view or edit the directory block by 


entering block 0, or other numbers for data blocks. If you enter"n", you can 
enter the edit mode without loading a block. 


Press enter to scroll the screen or press the space bar to single-step through 
the buffer. 


The bar across the left side of the screen is the address of the line that can 
be edited. Press "n" to enter a new number, "c" to enter a character or entire 
character string or file name. 

To go to a new address in the buffer, press "g" then the address. You can 
not go beyond the limits of the buffer. The buffer starts at50000. So, if you 
wantto go to the 4500" address in the buffer to see the disk name then enter 
54500. 


Pressing "f" will let you search for a byte such as the net 255 marker or a 
character by entering that character's code. 


To save the buffer back to the disk, press "s". You can load a block or 
catalogue from one disk and then save it to another disk. 


To exit the main menu, press "q". 


READ Disk Headers 


This will printto the screen or to a printer all the data headers of all the data 
tracks. This is useful if you wantto find the start and length of a code file or to 
find the blocks used by files when you are reconstructing a damaged directory. 
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The printer option prints to the Timex/Sinclair 2049 thermal printer unless you 
open channel 3to a line printer or load a printer driver. 


Change Disk Speed 


This allows the head speed on a disk to be changed to a different value. 
Pressing "4" aborts. 


Reformat A Single Block 


A block can be damaged by turning on the drive power when a disk is in it or 
by numerous other ways. You can reformat a single block using this option. 
Because the format code is the only code that can be used on a specific 
interface, you must insertthe Disk Editor disk and load the format code before 
actually formatting. After the code has been loaded once though, you can enter 
"z" to suppress further loadings of the format code. 


Initialize Directory 


With this option you can initialize the directory and the track map but you can 
not changethediskname. Warning: thiscommand will wipe out all the files on 
the disk. 


Map-Out Bad Blocks 


A disk that has bad blocks caused by a scratch or other physical defect can 
be automatically mapped as "unused" by this command. However, you should 
first make sure that the disk is the true source of the CRC errors andnota 
hardware problem. A common source for false CRC error reports is the board in 
the command cartridge dock. Sometimes, after sitting in the command cartridge 
dock for a time, the edge connector on this board becomes dirty or corroded and 
fails to make proper contact with the computer. Cleaning the edge connector 
will correct this problem buttake care to shutdown and remove the power cable 
from your Timex/Sinclair 2068 before removing the board from the command 
cartridge dock. Failing to do this will irreparably damage your computer and put 
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you at risk of receiving an electric shock. A disk that clicks while rotating in the 
drive usually has a surface defect. 


Change Disk Name 


You can change the disk name withoutaltering anything else on the disk 
using this option. You could even break the program and load the disk name 
from a word processor file to address 53500, then save the buffer. Tasword Ip 
can not be used because it formats each line as a 64 character array. Jack 
Dohany's, (but not the original!), version of M-Script® which has been modified 
for LARKEN I/O works well. 


Catalogue / Go To Drive (Now 0) 


This command allows you to change drives and display the catalogue. If 
you do notwantto change drives then just press enter. 


Display The Track Map 


This command bring up a graphic representation of the track map. The 
vertical numbers represent "tens" and the horizontal numbers are "ones". This 
gives you a picture of the state of the disk. If many files have been deleted you 
will see how LKDOS keeps track of unused tracks. 


Note: 


You can break and alter the program as you wish. It issafeto RUNit. Most of 
the editor option runs as compiled BASIC (compiled with Time Machine at 
60000). The compiled section begins at line 910 and ends at 1450. 


LKDOS Machine Language Sub-Routines 


The following information is for directly using the routines within LKDOS to 
control the disk drive. They are useful for examining or changing dataon the 
disk and also you can create custom files and simulate random access files and 
so forth. 
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To access LKDOS subroutines within the cartridge directly, you must use 
machine language. 


To call these sub-routine you mustfirst turn on the cartridge with a call to 
address 98d. The cartridge is tuned off by a memory read at address 100d. 


You should also disable the interrupts before entering and enable them after 
your are done. 


An example for accessing the cartridge: 


DI 
CALL 98 


CALL LKDOS subroutine 
other code 

LD A,(100) 

El 

RET 


Description Of Useful Sub-Routines 


The addresses of these sub-routines are on the following pages. The jump 
table of calls is used so that the addresses of the main routines do not change 
when a change or revision is made to the LKDOS EPROM. Also, because of 
the size of LKDOS, it was assembled in two modules. The second module uses 
the table to like to the first module. 


SAVEBF Saves the buffer to the currenttrack and side as set up by 
TRACK or NEXTR. The disk should be spinning for 1 second 
before using this routine. You can load data to and from the 


buffer using the LDIR command in machine language. 


LOADBF Loads the buffer from the current track and side. 


TRACK Restores the drive head to track 0 then seeks the track held in 
curtrk. The number in curtrk is actually the block number. 
Even blocks are side 0 and odd blocks are side 1. The track 
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TRACK routine so be sure to only place data in the buffer after 
calling TRACK. 


NEXTR Increments curtrk by one and moves the head to the next track 
or side. The drive should be running before this is called. 


INDIR Sets the head on track 0, loads the directory track, then 
searches for a file name matching the one the user has put at 
prognm. The temp2 pointer hold the address of the file name if 
found. Errnu will contain 10 if the file was not found. Clear 
errnu before calling thiscommand. Pad the file name with 


spaces if itis less than 10 characters. 


WPROT Does a 0.75 second spin up then checks if the disk has been 
write protected. If the disk is write protected then the program 
is halted andan error statement S - Protect Error is printed. 
Because this sub-routine does halt the program upon an error 


number is equal to INT(block/2). Example: block 11 equals 
track 5 side 1. TRACK also does the 1 second spin up 
required by save and load routines. It should be the first call in 
any disk access. The data in the buffer may be erased by the 


and thereby causing a possible loss of data, itis best to check if 
the disk is write protected before inserting it into the disk drive. 


DECDP Prints the contents of temp1 andthe accumulator as a decimal 
number. 


DOSER This will printa standard type error in the same manner as the 
Timex/Sinclair does when running in native mode. The HL 
register should hold the address of the error message and the 


message should end with a period. 


EVALU This is used to evaluate a BASIC numeric expression in a 
BASIC command. CHADD should pointto the start of the 
number of formula. Use RST #20 to move CHADD. The 
result will returned in the BC register. EVALU uses the Sinclair 
ROM calls to do this very complicated mathematics. It checks 
to see if you are running in Timex/Sinclair 2068 mode or in ZX 
Spectrum mode and then does the appropriate ROM call. 


GTFIL This is like the EVALU butis for string expressions. CHADD 
should pointto one character before the string before GTFIL is 
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called. The result string will be in fond in the variable prognm. 
The DE register will point to the final quote of the string. If the 
intension is then to search file names for the string using INDIR 


then the final quote must be removed by executing LD A,32; 
LD(DE),A immediately after calling GTFIL. 
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Saving And Loading Programs From Machine Code 


You can access the main operating system directly by the following four 
sub-routines. This will allow you to write or modify fully machine code programs 
to use the disk just as you can in BASIC. BASIC and ARRAY saves require a 
lot of variable shuffling. For this reason, only CODE saves will be described 
here. 


When you send LKDOS a command in BASIC, LKDOS scans the line forthe 
information itneeds. Butin machine code, we must put the information in 
certain locations then call LKDOS to use it. 


The LKDOS location NmiF is used to tell LKDOS how it is being called, i.e. 
NIM, BASIC or from a machine code program. It shouldbe loaded with 11d 
before you call the following routines. 


Saving Files From Machine Code 


To save an area of memory to disk from machine code, you must first give it 
a file name and transfer the file name to prognm. The file name should be a 
code type but because there is no syntax checking, any name and extension will 
work. In other words, you are notlimited to A. .B or .C type files. 


Then call the SV#1 sub-routine. This will enter the file name into the 
directory and fill the directory work area with free blocks to use for saving If the 
file already exists then the old file is deleted first. 


Now, load temp2 with the length of the file and temp4 with the start address 
of the file. Then call SV#2 to finish the save. 


Example:To save a file named text.ZZ with start address at 30000 anda 


length of 10000 bytes: 
Save DI Disable interrupt. 
CALL 98 Turn on the cartridge. 


LD HL,Name Transfer file name 
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LD DE,prognm to program. 


LD BC,10 

LDIR 

LD A,11 Set MC save. 

LD (NmiF),A 

CALL SV#1 Save name. 

LD HL,30000 

LD (temp4),HL Set start address. 

LD HL,10000 

LD (temp2),HL Set length of save. 

CALL SV#2 Second data. 

LD A,(100) Exit cartridge. 

El 

RET 
Nam  DEFM ftestZZ / Name of file padded to 10 
e characters. 


The SV#1 main routine first call the WPROT sub-routine to see if the disk is 
protected. If the disk is protected then it will terminate with an error. This will 
stop the machine code program. 


If you do not wish your machine program to be stopped then the best way 
around this is to find the address of the actual SV#1 routine in the EPROM by 
reading locations 205 and 206. Add 3 to the address to skip past the WPROT 
call then call the new address directly. This address must be calculated 
dynamically because it may change with new EPROM revisions. 


if you are saving a file from one address by wantthe files absolute load 
address, that is, LOAD "file" CODE - no address specified), then you should 
change the locations Destin and Totlen on the first block of the file to reflect the 
new start or length. Also, if you are adding data to the end of a file such as 
sequential files, you mustupdate Totlen on the first block of the file. 


If the file is a BASIC or ARRAY file then the first and last blocks should have 


their pointers updated. 


Loading A File From Disk 
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loading a file from machine code is similar to saving. Justuse LD#1 instead 
of SV#1 and LD#2 instead of SV#2. The start and length still go into temp4 and 
temp2. The filename is also moved into place the same way. 


If you wantto use the start address and length thatthe file was saved from 
to load it then after calling LD#1, (the first block of the file is now in the buffer), 
use the Destin and Totlen pointers as your start and length. 


You can poke 23728,100 as you do in BASIC so your program will notstop 
with a File Not Found error. 
Selecting Drives From Machine Code 

The LKDOS variable Dvsel indicates which drive is currently active. You 


may change the currentdrive by changing the value of Dvsel according to the 
following list. 


1 = drive 0 
2 = drive 1 
4 = drive 2 
8 = drive 3 


128 = drive 4 (RAM Disk) 


When changing drives, (especially floppies), inserta 0.05 second delay 
before and after changing drives between any disk call. 


Machine Code Programming Guidelines For LKDOS 


If you plan on writing a program your yourself or other LKDOS users then to 
be fully compatible with other programs or changes that may be forthcoming the 
following simple rules should be followed. 


1)Using the calls to the jump table in the cartridge will keep 
compatibility among users of differentinterfaces such 
as Aerco, Ramex and others. Do notuse the format 
code th at is supplied with the format program. 


13 


Larken Disk Editor 


First Draft 


2)When searching through the directory track, always use a 


linear search string at the start of the track map and 
search byte by byte. Never expect the length of the 
track map to always be 165 bytes long or the offset 
between names cells to be exactly 34 bytes. These 
can change and are designed to be changeable. 


A Simple Machine Code Program 


Free Blocks 


This routine allows you to find the number of free blocks without displaying 
the catalogue. It will return the number of free blocks in the BC register so it can 
be accessed from BASIC with PRINT USR FREEBL or LET x = USR FREEBL. 


FREEB DI 


L 


USED 


EXIT 


RET 


CALL,98 
LD A,0 
LD (curtrk),A 


CALL TRACK 


CALL 
LOADBF 
LD C,0 

LD HL,data 
INC HL 

LD A,(HL) 
CP 255 

JR Z,EXIT 
CP 245 

JR Z,USED 
INC C 

JR USED 
LD B,O 

LD A,(100) 


Turn on the LKDOS cartridge 


Move the disk drive to 
block O (side 0, track 0) 
Load disk to buffer 


Set counter to 0 
Set HL to the start of the track map 
First block always used anyway 


255 means "end of track map" 

If so then exit 

254 marker means "block used" 

If so then on to the next one 

Must be a free block, update count 
Continue searching for free blocks 


Turn the LKDOS cartridge off 
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LKDOS Addresses And Sub-Routines for Machine Language (USER) 


Programs 


Locations Used by LKDOS Calls 


Nmif 
Dvsel 
Hspd 
Rbank 
Radar 
Chars 
wrkspc 
buffer 
data 
curtrk 
ermu 
prognm 
temp 1 
temp2 
temp4 
temp6 
dirwka 


destin 
lenth 
Linenu 
Vofset 
Totlen 


Buffer Length 


5114 
1984 


EQU 8194 

EQU 8195 

EQU 8202 

EQU 8203 

EQU 8204 

EQU 8218 

EQU 8220 

EQU wrkspc + 84 
EQU buffer + 24 
EQU wrkspc + 1 
EQU wrkspc + 4 
EQU wrkspc + 6 
EQU wrkspc + 20 
EQU wrkspc + 21 
EQU wrkspc + 23 
EQU wrkspc + 25 
EQU wrkspc + 30 


*** These registers are saved with each track **** 


EQU buffer+ 12 
EQU buffer + 14 
EQU buffer + 17 
EQU buffer + 20 
EQU buffer + 22 


Data Length 


5090 Standard double-density controller 
Old single-density controller 


1960 


Nmi, USER or BASIC flag 
Drive select byte (1770) 
Head speed for FD1770 
RAM disk bank number 
RAM disk bank address 


Address of window character set - 256 


Start of disk work space 

Start of track buffer 

Start of actual data block 

Block number for head to seek 
Holds 0 if no error has occurred 
Holds string from Gtfil 


Used by DECDMP 


Usually holds the length of a file 
Start address of file 

Temporary address 

Holds cell being used 


Address of data block 
Length of data block 
Auto-run BASIC line 
Vars Offset (Vars-Prog) 


Total length of file 
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LKDOS Main Sub-Routine Jump Table 


This is the LKDOS main sub-routine jump table. Each call is 3 bytes apart. 
These addresses are unaffected by any changes or revisions made later to 
LKDOS. The jump table starts at address 120d. 


KKKKKKK CALL KKKKKKK 


SAVEBF 


LOADB 
F 
TRACK 
NEXTR 
INDIR 
MOVDR 
CMDCK 
ENDLN 
EVALU 
NOFIL 
WPROT 
ZERO 
GTFIL 
ROMM 
NEWET 
DECDP 


TRANO 
K 
DOScp 


DOSER 
CLRBF 
ENCOD 
VSERC 
H 
JPOUT 
GROW 
SHrnk 
DTERR 
LD#1 


JP crcsv 
JP loadbf 


JP trac 

JP nextrk 
JP indir 
JP movdr 
JP cmdck 
JP Endoln 
JP Evalu 
JP nofil 
JP WPROt 
JP zer 
JP Gtfil 
JP ROMS 
JP newet 
JP 
decdmp 
JP tranok 


JP 
DOSOP 
JP Doserr 
JP clrbf 
JP encdbf 
JP vserch 


JP GTOUT 
JP Grow 
JP Shrink 
JP Fatal 
JP Lsubr 


ADD 


R 
120 
123 


126 
129 
132 
135 
138 
141 
144 
147 
150 
153 
156 
159 
162 
165 


168 


171 


174 
177 
180 
183 


186 
189 
192 
195 
198 


Description 


Save the bufferto the disk 
Load the buffer from the disk 


Restore Trk0 then seek current track 
Increment disk head 1 track or side 
Check directory for file (in prognm) 
Move cell to dirwka 

Check command syntax 

Move CHADD to the end of BASIC line 
Evaluate numeric formula 

No file error 

Check if the disk is write protected 
Restore blocks used by cell 
Evaluate string, putin prognm 
Checks for the ZX Spectrum ROM 
Put new entry into the directory 
Printtemp1 in decimal 


Final routine forsave 
Close the disk channel 


Printerror. HL holds the message 
Clear the buffer 

Encode the buffer with addresses 
Look for arrays 


Exit the LKDOS cartridge 

Insert space in program 

Delete space in program 
Catalogue data error 

First half of userload command 
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kkkkkkk CALL kkkkkkk ADD 


R 
LD#2 JP LDdata 201 Second half of user load command 
SV#1 JP Ssubr 204 First half of user save command 
SV#2 JP SMEM 207 + Second half of user save command 


Description 


Note: 
Most of the cartridge RAM is used by LKDOS and Extended BASIC (Ex-BASIC), 


however, the merge buffer can be used for temporary storage. The merge 
buffer follows the data buffer andis 1200 byes long. 
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